History Rollups
Historical data in the VHS is stored in its raw format. A rollup refers to the process of taking the raw data from the VHS and condensing it using a calculation or by thinning. The VHS uses an iterator to traverse a list of entries in a VHS and "roll" the values up, effectively compressing the data retrieved in a manner indicated by the rollup type chosen. The iterator is used by several applications in CygNet Software, including:
- visualizing data on a CygNet Trend Tool in CygNet Studio (See Editing a Series)
- visualizing aggregated data on a Default Trend
- presenting aggregated data in summary nodes in the Group service
- presenting data in the Group Grid in CygNet Studio (see Columns)
- display station and group levels rollups in CygNet Measurement clients
- viewing rolled up forecasted gas load values for a meter group in Energy Load Forecasting
- display rollups in nodes in the General Contract Monitor
- retrieving data for CygNet Business Operations (using the Business Object Builder)
- supported in CygNet Native Operations (History and Point)
- exporting history data with CygNet Excel Export
- exporting history data with the CygNet History Export Utility
- reporting history data with the CygNet Report Module
- writing ODBC queries via the HistoryRollup stored procedure
- scripting rollups using CxVhsClient and CxVhsLib.RollupIterator and CxVhs.VhsDatastoreInterface
- scripting tag rollups in the CxGrpGrid
Also refer to CygNet.API.Historian.Client (GetDailyRollup, GetHourlyRollup, GetHistoricalRollup, HistoricalRollupEnumerable) and CygNet.Data.Historian.HistoricalEntry (HistoricalRollupType Enumeration, HistoricalRollupUnit Enumeration) in the CygNet.API.chm Help file for CygNet.API .NET usage.
Also see Notes about History Rollup for information and examples about rollups.
Rollup Parameters
There are several required parameters that must be passed to the rollup iterator when configuring rollups, either via UI configuration or script. In some applications the parameter's name is slightly different, depending on the user or script interface being used, and is noted in the table below.
| Parameter Names | Description |
|---|---|
|
Rollup Period rollupPeriod RollupPeriod |
Specifies the time interval by which a rollup type takes place. The rollup period refers to the quantity of units in a period. For example, to rollup 30 days, the RollupPeriod is 30 and the RollupUnit is "days." |
|
Rollup Type rollupType RollupType |
Specifies the type by which to roll up data for a selected point. The possible values are listed in CxRollupType or in CygNet.Data.Historian.HistoricalRollupType. See Rollup Type below. |
|
Rollup Units rollupUnits RollupUnits |
Specifies the time units by which a rollup takes place. This refers to time increments, such as seconds, minutes, hours, or days. The possible values are listed in CxRollupUnits or in CygNet.Data.Historian.HistoricalRollupUnit. |
|
Tag TagString |
The point tag from which data is being retrieved in valid CygNet tag string format. |
|
Earliest Time earliestTime EarliestTime StartTime TimeStampEarliest |
The starting date and time of the retrieval period, or how far back to go for data. The date range can be specific or you can use date wildcards. See Rules of EarliestTime and LatestTime for more information. |
|
EndTime Latest Time latestTime LatestTime TimeStampLatest |
The ending date and time of the retrieval period, or the most recent date. The date range can be specific or you can use date wildcards. See Rules of EarliestTime and LatestTime for more information. |
|
Top of SubUnit Top of Sub-Unit TopOfDayHour TopOfSubUnit TopSubUnit topSubUnit |
The offset value to use if the subunit to the major unit does not start at the time unit expected. Subunit means whatever unit of time is the next smaller than that defined in RollupUnits.(i.e. hours to a day, minutes to an hour). This provides a method to allow for differences in start of day, time zone, or scheduling. For example, to accommodate contract days starting at 5 AM, the TopOfDayHour would be 5 (indicating 5 hours from midnight). See Offset Notes for more information. |
|
Historian.Name VHS Site.Service VhsSiteService |
The site and service name of the VHS point tag, in "site.service" format. |
Rollup Type
The following table describes the rollup types that are supported by CygNet. Points with blank values, non-numeric values (for example, string value = "BOB"), and pseudo-numeric values (for example, enumerated value = "1:ENABLED") are handled differently for each rollup type. The last four columns of the table describe how the VHS uses these history values when returning data for each rollup type.
| Rollup Type | Description | Value is Used If... | |||
|---|---|---|---|---|---|
| Numeric | Blank | Non-Numeric | Pseudo-Numeric | ||
|
Raw Data |
Returns raw data from the VHS. |
|
|
|
|
|
Calculated Weighted Average |
Returns a time-weighted rolling average for the range with a timestamp that reflects the end of the rollup interval. For example, if the data window is a three-day period and the rollup interval is one day, the result would be one value per day that represents a time-weighted average for the three-day period. |
(calculated) |
|
|
Uses numeric portion of value to calculate weighted average |
|
Calculated Mean |
Returns a simple average of the values for the range with a timestamp that reflects the end of the rollup interval. |
(calculated) |
|
|
Uses numeric portion of value to calculate mean |
|
Calculated Min |
Returns the minimum value for the range with a timestamp that reflects the end of the rollup interval. |
(calculated) |
|
|
Uses numeric portion of value to calculate minimum |
|
Calculated Max |
Returns the maximum value for the range with a timestamp that reflects the end of the rollup interval. |
(calculated) |
|
|
Uses numeric portion of value to calculate maximum |
|
Calculated Delta |
Returns the difference between the minimum and maximum values for the range. If there is no difference, the returned value is zero. |
(calculated) |
|
|
Uses numeric portion of value to calculate delta |
|
Calculated Last |
Returns the last value received for the range. |
|
|
|
(last) |
|
Thin Median |
Returns the middle value from the set of values for the range. If there is an even number of values collected, the value returned is the one that falls before the true middle. If no values are collected, no values are returned. See Thin Rollup Types for more information. |
(middle) |
|
|
(middle) |
|
Thin Min/Max |
Returns the minimum and maximum values for the range. If only one value is collected, it returns the value. If no values are collected, no values are returned. |
(min and max) |
|
|
(numeric portion) |
|
Thin Last |
Returns the last value collected for the range. If no values are collected, no values are returned. |
(last) |
|
|
(last) |
About Timestamps and Rollups
The timestamp for a Calculated Rollup is the timestamp for the end of the rollup interval.
The timestamp for a Thinned Rollup is the value’s actual timestamp. Since the timestamp for a thinned rollup is the value’s actual timestamp, the timestamp may be outside of the data window if the value occurred before the period. For example, the value hasn’t changed for two days. Even though the data window is only the current day, the timestamp of the value would be from two days ago.
If a change is detected in a history point version, the VHS forces a recalculation of the rollup, eliminating possible "stale" history data in a rollup. The rollup recalculation is triggered for a history point when either the history point version has changed, or the VHS startup timestamp has changed.
History Rollups Dialog Box Scripting
The following scripting options are available for data interface functions related to the History Rollups dialog box.
| COM API | Description and Link |
|---|---|
|
CxDialogs CxScript |
The ShowRollupConfigDialog method displays the History Rollup Configuration dialog box.
|
